Add `format` option to `paginate()` for customizing pagination URLs by astrobot-houston · Pull Request #17258 · withastro/astro

astrobot-houston · 2026-07-01T19:36:35Z

Changes

Adds a format option to PaginateOptions that accepts a (url: string) => string callback. When provided, it is applied to all pagination URLs (current, next, prev, first, last) after they are constructed.
This is a non-breaking, opt-in addition — default behavior is completely unchanged. Users deploying to static file servers without URL rewrite rules can now use this to append .html (or apply any other transformation) to pagination URLs generated by paginate().

paginate(items, {
  pageSize: 10,
  format: (url) => `${url}.html`,
})

Closes #13604

Testing

Added 3 new describe blocks (8 test cases) to packages/astro/test/units/render/paginate.test.ts covering: format applied to all URL properties, format skipped for undefined URLs, format applied after base path is prepended, and no regression when format is omitted.

Docs

The new format option is documented inline via JSDoc on PaginateOptions. A docs-site update to the paginate() reference may be warranted to surface this option for users hitting 404s on static file servers.

withastro/docs#14201

@withastro/maintainers-docs for feedback

changeset-bot · 2026-07-01T19:36:42Z

🦋 Changeset detected

Latest commit: 4c1e197

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 395 packages

Name	Type
astro	Minor
@e2e/astro-linked-lib	Patch
@e2e/actions-blog	Patch
@e2e/actions-react-19	Patch
@e2e/astro-component	Patch
@e2e/astro-envs	Patch
@e2e/astro-island-hydration-error	Patch
@test/astro-cloudflare-node-prerender-mdx	Patch
@test/astro-cloudflare	Patch
@e2e/content-collections	Patch
@e2e/csp-server-islands	Patch
@e2e/css	Patch
@test/custom-client-directives	Patch
@e2e/dev-toolbar	Patch
@e2e/error-cyclic	Patch
@e2e/error-sass	Patch
@e2e/errors	Patch
@e2e/hydration-race	Patch
@e2e/i18n	Patch
@test/nested-style-bug-e22e	Patch
@e2e/preact-compat-component	Patch
@e2e/preact-component	Patch
@e2e/preact-lazy-component	Patch
@e2e/prefetch	Patch
@e2e/react-component	Patch
@e2e/server-islands-key	Patch
@e2e/server-islands	Patch
@e2e/solid-circular	Patch
@e2e/solid-component	Patch
@e2e/solid-recurse	Patch
@e2e/svelte-component	Patch
@e2e/e2e-tailwindcss	Patch
@e2e/ts-resolution	Patch
@e2e/view-transitions	Patch
@e2e/vite-virtual-modules	Patch
@e2e/vue-component	Patch
@performance/md	Patch
@performance/mdoc	Patch
@performance/mdx	Patch
@test/0-css	Patch
fake-astro-library	Patch
@test/actions	Patch
@test/alias-css-url	Patch
@test/alias-path-alias-style	Patch
@test/ts-paths-no-baseurl	Patch
@test/aliases-tsconfig	Patch
@test/aliases	Patch
@test/api-routes	Patch
@test/asset-query-params-chunks	Patch
@test/asset-url-base	Patch
@test/astro-pages	Patch
@test/astro-assets-prefix	Patch
@test/astro-assets	Patch
@test/astro-basic	Patch
@test/astro-check-errors	Patch
@test/astro-check-no-errors	Patch
@test/astro-check-watch	Patch
@test/astro-children	Patch
@test/astro-client-only	Patch
@test/astro-component-bundling	Patch
@test/astro-component-code	Patch
@test/astro-css-bundling	Patch
@test/astro-dev-headers	Patch
@test/astro-dev-http2	Patch
@test/astro-doctype	Patch
@test/astro-dynamic	Patch
@test/astro-env-content-collections	Patch
@test/astro-env-required-public	Patch
@test/astro-env-server-fail	Patch
@test/astro-env-server-secret	Patch
@test/astro-env	Patch
@test/astro-envs	Patch
@test/astro-expr	Patch
@test/astro-get-static-paths	Patch
@test/astro-head	Patch
@test/astro-manifest-client-script	Patch
@test/astro-manifest-invalid	Patch
@test/astro-manifest	Patch
@test/astro-markdown-frontmatter-injection	Patch
@test/astro-markdown-plugins	Patch
@test/astro-markdown-remarkRehype	Patch
@test/astro-markdown-skiki-default-color	Patch
@test/astro-markdown-skiki-langs	Patch
@test/astro-markdown-skiki-themes-custom	Patch
@test/astro-markdown-skiki-themes-integrated	Patch
@test/astro-markdown-skiki-wrap-false	Patch
@test/astro-markdown-skiki-wrap-null	Patch
@test/astro-markdown-skiki-wrap-true	Patch
@test/astro-markdown-url	Patch
@test/astro-markdown	Patch
@test/astro-mode	Patch
@test/astro-page-directory-url	Patch
@test/astro-partial-html	Patch
@test/astro-preview-allowed-hosts	Patch
@test/astro-preview-headers	Patch
@test/astro-public	Patch
@test/astro-script-template-dedup	Patch
@test/astro-scripts	Patch
@test/astro-slots-nested	Patch
@test/concurrency	Patch
@test/build-readonly-file	Patch
@test/cache-memory-query-include	Patch
@test/cache-memory-query	Patch
@test/client-address-node	Patch
@test/client-only-css-chunk-leak	Patch
@test/code-component	Patch
@test/component-library	Patch
@test/config-vite-css-target-no-minify	Patch
@test/config-vite-css-target	Patch
@test/config-vite	Patch
@test/react-container	Patch
@test/content-with-spaces-in-folder-name	Patch
@test/content-collection-picture-render	Patch
@example/content-collection-references	Patch
@test/content-collection-tla-svg	Patch
@test/content-collections-base	Patch
@test/content-collections-empty-dir	Patch
@test/content-collections-empty-md-file	Patch
@test/content-collections-image-hmr	Patch
@test/content-collections-mutation	Patch
@test/content-collections-number-id	Patch
@test/content-collections-type-inference	Patch
@test/content-collections-with-config-mjs	Patch
@test/content-collections	Patch
@test/content-frontmatter	Patch
@test/content-intellisense	Patch
@test/content-layer-loader-schema-function	Patch
@test/content-layer-remark-plugins	Patch
@test/content-layer	Patch
@test/content-ssr-integration	Patch
@test/content-static-paths-integration	Patch
@test/content	Patch
@test/core-image-data-url	Patch
@test/core-image-deletion-ssr	Patch
@test/core-image-deletion	Patch
@test/core-image-errors	Patch
@test/core-image-fs-config	Patch
@test/core-image-remark-infersize	Patch
@test/core-image-layout	Patch
@test/core-image-picture-emit-file	Patch
@test/core-image-remark-imgattr	Patch
@test/core-image-ssg	Patch
@test/core-image-ssr	Patch
@test/core-image-svg-in-client	Patch
@test/core-image-svg	Patch
@test/core-image-unconventional-settings	Patch
@test/core-image	Patch
@test/csp-adapter	Patch
@test/csp-fonts	Patch
@test/csp	Patch
@test/css-assets	Patch
@test/css-dangling-references	Patch
@test/css-deduplication	Patch
@test/css-double-bundle	Patch
@test/css-dynamic-import-dev	Patch
@test/css-import-as-inline	Patch
@test/css-inline-stylesheets	Patch
@test/css-no-code-split	Patch
@test/css-path-case	Patch
@test/css-pure-chunk-query-params	Patch
@test/custom-404-injected-from-dep	Patch
@test/custom-404-pkg	Patch
custom-fetch-error-pages	Patch
@test/custom-renderer	Patch
@test/data-collections-schema	Patch
@test/data-collections	Patch
@test/debug-component	Patch
@test/dev-container	Patch
@test/dev-render	Patch
@test/dev-request-url	Patch
@test/dynamic-endpoint-collision	Patch
@test/dynamic-route-build-file	Patch
@test/endpoint-routing	Patch
@test/error-bad-js	Patch
@test/error-build-location	Patch
@test/error-non-error	Patch
@test/extension-matching	Patch
@test/fetch	Patch
@test/fonts	Patch
@test/astro-fontsource-package	Patch
@test/get-static-paths-pages	Patch
@test/glob-pages-css	Patch
@test/head-propagation-prerender-env	Patch
@test/hmr-markdown	Patch
@test/hmr-new-page	Patch
@test/hmr-slots-render	Patch
@test/hoisted-imports	Patch
@test/html-component	Patch
@test/html-escape	Patch
@test/html-page	Patch
@test/html-slots	Patch
@test/hydration-race	Patch
@test/i18n-client-import	Patch
@test/i18n-css-leak-basic	Patch
@test/import-ts-with-js	Patch
@test/impostor-md-file	Patch
@test/integration-add-page-extension	Patch
@test/integration-server-setup	Patch
@test/jsx-queue-rendering	Patch
@test/large-array-solid	Patch
@test/legacy-collections-backwards-compat	Patch
@test/lightningcss-scoped-nesting	Patch
@test/live-loaders	Patch
@test/markdown	Patch
@test/middleware-dev	Patch
@test/middleware-full-ssr	Patch
@test/middleware-no-user-middlewaqre	Patch
@test/middleware-tailwind	Patch
@test/minification-html-default	Patch
@test/minification-html-jsx	Patch
@test/minification-html	Patch
@test/non-ascii-path	Patch
@test/non-html-pages	Patch
@test/page-format	Patch
@test/page-level-styles	Patch
@test/parallel-components	Patch
@test/partials-css-boundary	Patch
@test/partials	Patch
@test/passthrough-image-service	Patch
@test/postcss	Patch
@test/preact-compat-component	Patch
@test/preact-component	Patch
@test/remote-css	Patch
@test/request-signal	Patch
@test/reuse-injected-entrypoint	Patch
@test/root-srcdir-css	Patch
@test/scoped-style-strategy	Patch
@test/server-entry-fake-adapter	Patch
@test/server-entry	Patch
@test/server-islands-hybrid	Patch
@test/server-islands-ssr	Patch
@test/sessions	Patch
@test/slots-preact	Patch
@test/slots-react	Patch
@test/slots-solid	Patch
@test/slots-svelte	Patch
@test/slots-vue	Patch
@test/solid-component	Patch
@test/sourcemap	Patch
@test/space-in-folder-name	Patch
@test/special-chars-in-component-imports	Patch
@test/ssr-assets	Patch
@test/ssr-dynamic	Patch
@test/ssr-partytown	Patch
@test/ssr-prerender-get-static-paths	Patch
@test/ssr-prerender	Patch
@test/ssr-preview	Patch
@test/ssr-renderers-static-vue	Patch
@test/ssr-request	Patch
@test/ssr-hoisted-script	Patch
@test/ssr-scripts	Patch
@test/static-build-code-component	Patch
@test/static-build-dir	Patch
@test/static-build-frameworks	Patch
@test/static-build-page-url-format	Patch
@test/static-build-ssr	Patch
@test/static-build	Patch
@test/static-redirect	Patch
@test/svelte-component	Patch
@test/svg-deduplication	Patch
@test/tailwindcss	Patch
@e2e/third-party-astro	Patch
@test/url-import-suffix	Patch
@test/view-transitions	Patch
@test/virtual-astro-file	Patch
@test/vitest	Patch
@test/vue-component	Patch
@test/vue-with-multi-renderer	Patch
@test/alpinejs-basics	Patch
@test/alpinejs-directive	Patch
@test/alpinejs-plugin-script-import	Patch
@test/astro-cloudflare-allowed-hosts	Patch
@test/astro-cloudflare-astro-dev-platform	Patch
@test/astro-cloudflare-astro-env	Patch
@test/astro-cloudflare-binding-image-service	Patch
@test/astro-cloudflare-cache-provider-wait-until	Patch
@test/astro-cloudflare-cache-provider	Patch
@test/astro-cloudflare-client-address	Patch
@test/astro-cloudflare-compile-custom-image-service	Patch
@test/astro-cloudflare-compile-image-service	Patch
@test/astro-cloudflare-custom-entryfile	Patch
@test/astro-cloudflare-dev-image-endpoint	Patch
@test/astro-cloudflare-external-image-service	Patch
@test/astro-cloudflare-external-redirects	Patch
@test/astro-cloudflare-internal-redirects	Patch
@test/astro-cloudflare-no-output	Patch
@test/astro-cloudflare-prerender-node-env	Patch
@test/astro-cloudflare-prerender-queue-consumers	Patch
@test/astro-cloudflare-prerender-styles	Patch
@test/astro-cloudflare-prerenderer-errors	Patch
@test/astro-cloudflare-prerenderer-render-error	Patch
@test/routing-priority-cloudflare	Patch
@test/cf-server-entry	Patch
@test/astro-cloudflare-server-island-prerender-framework	Patch
@test/astro-cloudflare-sql-import	Patch
@test/cf-ssr-deps	Patch
@test/astro-cloudflare-static	Patch
@test/astro-cloudflare-svelte-rune-deps	Patch
@test/astro-cloudflare-top-level-return	Patch
@test/cf-user-optimize-deps	Patch
@test/astro-cloudflare-vite-plugin	Patch
@test/astro-cloudflare-with-base	Patch
@test/astro-cloudflare-with-react	Patch
@test/astro-cloudflare-with-solid-js	Patch
@test/astro-cloudflare-with-svelte	Patch
@test/astro-cloudflare-with-vue	Patch
@test/astro-cloudflare-wrangler-preview-platform	Patch
@test/markdoc-content-collections	Patch
@test/content-layer-markdoc	Patch
@test/headings-custom	Patch
@test/headings	Patch
@test/image-assets-custom	Patch
@test/image-assets	Patch
@test/markdoc-propagated-assets	Patch
@test/markdoc-render-with-space	Patch
@test/markdoc-render-html	Patch
@test/markdoc-render-null	Patch
@test/markdoc-render-partials	Patch
@test/markdoc-render-simple	Patch
@test/markdoc-render-table-attrs	Patch
@test/markdoc-render-typographer	Patch
@test/markdoc-render-with-components	Patch
@test/markdoc-render-with-config	Patch
@test/markdoc-render-with-extends-components	Patch
@test/markdoc-render-with-indented-components	Patch
@test/markdoc-render-with-transform	Patch
@test/markdoc-variables	Patch
@test/content-layer-rendering	Patch
@test/mdx-css-head-mdx	Patch
@test/image-remark-imgattr	Patch
@test/mdx-astro-container-escape	Patch
@test/mdx-frontmatter-injection	Patch
@test/netlify-skew-protection	Patch
@test/netlify-hosted-astro-project	Patch
@test/nodejs-api-route	Patch
@test/nodejs-badurls	Patch
@test/nodejs-encoded	Patch
@test/nodejs-errors	Patch
@test/nodejs-headers	Patch
@test/nodejs-image	Patch
@test/locals	Patch
@test/node-middleware	Patch
@test/nodejs-prerender-404-500	Patch
@test/nodejs-prerender	Patch
@test/nodejs-prerendered-error-page-fetch	Patch
@test/nodejs-preview-headers	Patch
@test/redirects	Patch
@test/node-sessions	Patch
@test/ssr-assets-middleware	Patch
@test/node-static-headers	Patch
@test/node-trailingslash	Patch
@test/url	Patch
@test/well-known-locations	Patch
@test/react-component	Patch
@test/sitemap-chunks	Patch
@test/sitemap-dynamic	Patch
@test/sitemap-i18n-fallback	Patch
@test/sitemap-ssr	Patch
@test/sitemap-static	Patch
@test/sitemap-trailing-slash	Patch
async-rendering	Patch
conditional-rendering	Patch
@test/empty-class	Patch
svelte-prop-types	Patch
@test/astro-vercel-basic	Patch
@test/astro-vercel-image	Patch
@test/astro-vercel-integration-assets	Patch
@test/vercel-isr	Patch
@test/vercel-max-duration	Patch
@test/vercel-edge-middleware-with-edge-file	Patch
@test/vercel-edge-middleware-without-edge-file	Patch
@test/astro-vercel-no-output	Patch
@test/astro-vercel-prerendered-error-pages	Patch
@test/astro-vercel-redirects-serverless	Patch
@test/astro-vercel-redirects	Patch
@test/vercel-server-islands	Patch
@test/astro-vercel-serverless-prerender	Patch
@test/astro-vercel-serverless-with-dynamic-routes	Patch
@test/astro-vercel-static-assets	Patch
@test/vercel-static-headers	Patch
@test/astro-vercel-static	Patch
@test/vercel-streaming	Patch
@test/astro-vercel-with-web-analytics-enabled-output-as-static	Patch
vercel-hosted-astro-project	Patch
@test/vue-app-entrypoint-async	Patch
@test/vue-app-entrypoint-css	Patch
@test/vue-app-entrypoint-no-export-default	Patch
@test/vue-app-entrypoint-relative	Patch
@test/vue-app-entrypoint-src-absolute	Patch
@test/vue-app-entrypoint	Patch
@test/vue-basics	Patch
vue-prop-types	Patch
astro-benchmark	Patch
@benchmark/adapter	Major
@benchmark/timer	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

matthewp

missing a changeset and needs docs

Add a `format` option to `PaginateOptions` that accepts a callback `(url: string) => string` to transform pagination URLs (current, next, prev, first, last) before they are set on the page result. This allows users deploying to static file servers that don't support clean URLs to add file extensions like `.html`: paginate(items, { format: (url) => `${url}.html`, }) Fixes #13604

github-actions

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

ematipico · 2026-07-06T10:54:20Z

Added changeset and docs

codspeed-hq · 2026-07-06T10:56:31Z

Merging this PR will not alter performance

✅ 18 untouched benchmarks

_{Comparing triagebot/fix-13604 (4c1e197) with main (f94280d)¹}

No successful run was found on main (40dd725) during the generation of this report, so f94280d was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

ArmandPhilippot

A non-blocking suggestion, otherwise LGTM.

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

astrobot-houston added the fix verified Reporter confirmed the triage bot fix works label Jul 1, 2026

astrobot-houston mentioned this pull request Jul 1, 2026

Pagination not using .html files generated by build #13604

Open

1 task

github-actions Bot added pkg: astro Related to the core `astro` package (scope) docs pr labels Jul 1, 2026

matthewp requested changes Jul 1, 2026

View reviewed changes

matthewp added this to the 7.1 milestone Jul 2, 2026

astrobot-houston and others added 2 commits July 6, 2026 11:45

chore: add changeset

7a94fdf

ematipico force-pushed the triagebot/fix-13604 branch from daa9ae8 to 7a94fdf Compare July 6, 2026 10:49

github-actions Bot added the semver: minor Change triggers a `minor` release label Jul 6, 2026

github-actions Bot requested changes Jul 6, 2026

View reviewed changes

ematipico mentioned this pull request Jul 6, 2026

feat: format in paginate withastro/docs#14201

Open

ArmandPhilippot approved these changes Jul 6, 2026

View reviewed changes

Comment thread .changeset/pink-frogs-poke.md Outdated

Update .changeset/pink-frogs-poke.md

4c1e197

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

yanthomasdev approved these changes Jul 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add `format` option to `paginate()` for customizing pagination URLs#17258

Add `format` option to `paginate()` for customizing pagination URLs#17258
astrobot-houston wants to merge 3 commits into
mainfrom
triagebot/fix-13604

astrobot-houston commented Jul 1, 2026 •

edited by ematipico

Loading

Uh oh!

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

matthewp left a comment

Uh oh!

github-actions Bot left a comment

Uh oh!

ematipico commented Jul 6, 2026

Uh oh!

codspeed-hq Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

ArmandPhilippot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Uh oh!

Conversation

astrobot-houston commented Jul 1, 2026 • edited by ematipico Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Docs

Uh oh!

changeset-bot Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

matthewp left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ematipico commented Jul 6, 2026

Uh oh!

codspeed-hq Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

astrobot-houston commented Jul 1, 2026 •

edited by ematipico

Loading

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading

codspeed-hq Bot commented Jul 6, 2026 •

edited

Loading